Generate API Key

Note: Access to the 'Generate API key' function and using an API key to access the PlanningSpace APIs requires a user account to be granted the role 'Security/API Key' (see Roles).

Note: The 'Generate API key' function is part of the 'PlanningSpace Web' user interface. By default this is hidden from users; a PlanningSpace Web launch button can be enabled by the Administrator for your PlanningSpace tenant (with the setting 'Preview Web Features', see Tenant Settings). Otherwise, you can use a URL to directly access the 'Generate API Key' web page.

The API Key is a string token that you can use to access your PlanningSpace data using a Web API or OData connection. Its intended uses are for OData (also known as Integration Services) access, or for when the Web API is used for automation purposes. For more information, see the PlanningSpace Web API Documentation.

If your PlanningSpace user account is externally-authenticated (i.e., it is a SAML2-type user account, usually having the form 'firstname.lastname@domain.mycompany.com') then you can only use an API Key for OData API access; this includes using an external analysis tool such as Excel or Power BI.

Connect to the PlanningSpace tenant website

If the 'PlanningSpace Web' is visible with a launch button, you can login to your PlanningSpace tenant website (see Launch PlanningSpace), and click the PlanningSpace Web button:

After clicking the button, you should see an interface as below. Click the drop-down menu at the top right and select Generate API Key (but you will only see this option if your account is granted the role 'Security/API Key').

PS-tenant-PSWeb-GenerateAPIKey-1

You should see the Generate API Key page:

PS-tenant-PSWeb-GenerateAPIKey-2

URL for direct access

If the access buttons and menus are not visible: first login to the tenant website, and then you should be able to connect directly to the page with the URL:

https://SERVERADDRESS/TENANTNAME/PlanningSpace/#/generateApiKey

with your own values for 'SERVERADDRESS' and 'TENANTNAME' inserted.

Generate an API key

Click the Create key button to generate a new key.

PS-tenant-PSWeb-GenerateAPIKey-3

Click the Copy button next to the key field and immediately save the key in a safe location.

The key value is not stored in the PlanningSpace tenant, for reasons of security. If you lose the information you will need to generate a replacement key by re-visiting the web page.

Each PlanningSpace user account can support one API key. When you generate a new key, the previous one will be replaced. The PlanningSpace Administrator has the ability to delete the API Key for any user account.

Using an API key in an OData client

You can use an API key in a data analysis application where you would otherwise use a PlanningSpace Username and Password to connect via OData.

For example, in Excel 2016 Power Query you would set up a new OData Feed, and at the authentication step, you select the Basic option, and use 'FeedKey' as the User name and the API key as the Password:

The allowed user names are 'FeedKey' and 'Account Key'. These are the default values for the IPS server setting 'AllowedApiKeyNames' which can be changed by the IPS Administrator.